<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Pending Steps</title>
</head>

<body>

<h2>Pending Steps</h2>

<p>JBehave is designed to allow textual stories to be written
before the implementation, i.e. to let the specification of the
behaviour drive the development. For this reason, with steps that do not
match any method in the Steps class, which are called <b>pending
steps</b>, it does not fail by default. By marking a step as pending, it's
simply telling the scenario writer that it's not yet implemented and
correspondingly it will not execute any steps that following in the same
scenario.</p>

<p>In some cases, thought, it may be useful to make the scenarios
fail when steps are pending. The behaviour is controlled by configuring
the <a
    href="javadoc/core/org/jbehave/core/failures/PendingStepStrategy.html">PendingStepStrategy</a>
via the <a
    href="javadoc/core/org/jbehave/core/configuration/Configuration.html">Configuration</a></p>
<pre class="brush: java">
   Configuration configuration = new MostUsefulConfiguration()
        .usePendingStepStrategy(new FailingUponPendingStep());
</pre>

<span class="followup">Pending steps are steps that do not match any public Java method in the steps classes.
They should not be confused with steps marked as NOT PERFORMED that occur after a step failure.</span>

<h2>@Pending</h2>

<p>The <a
        href="javadoc/core/org/jbehave/core/annotations/Pending.html">@Pending</a> annotation allows
steps developers to mark any step method as pending:
</p>
 
<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
    @Given("a stock of symbol $symbol and a threshold of $threshold")
    @Pending
    public void aStock(String symbol, double threshold) {
        // not yet implemented
    }
 ]]>
</script>

<p>This would make the following textual step be marked as pending:
</p>

<pre class="brush: bdd">
Given a stock of symbol STK and a threshold of 10.0 (PENDING)
</pre>

<p>The intention of the @Pending annotation is to tell JBehave that the step has yet to be implemented.  
It is then by conscious choice that the Steps developer should remove the annotation when the step has been implemented.
</p>

<span class="followup">A method annotated with @Pending will always result in a pending step, 
overriding the matching that would result from the pattern provided in the @Given/@When/@Then annotations.
</span>

<h2>Dry Run Mode</h2>

<p>It may be sometimes useful to run in dry-run mode, checking if any steps are pending but without actually
executed any of the steps, as this may take a considerable time.  The dry-run mode may be enabled via
the <a href="javadoc/core/org/jbehave/core/steps/Configuration.html">Configuration</a>:</p>
 
<pre class="brush: java">
    Configuration configuration = new MostUsefulConfiguration()
	   .useStepMonitor(new PrintStreamStepMonitor()) // default is SilentStepMonitor()
	   .doDryRun(true); // default is "false"
    new InstanceStepsFactory(configuration, new MySteps());
</pre>

<p>We've here configured the steps to use a verbose monitoring, so that the use can see that in dry-run mode 
the step that is about to be performed will be followed by a "(DRY RUN)" additional tag.   When dry-run mode
is activated, it will also be shown in the reporters' output.
</p>

<h2>Troubleshooting</h2>

<p>If you are finding the methods are not being matched and the steps marked as pending, check that:</p>

<ul>
<li>the methods are <b>public</b></li>
<li>the method annotations <b>@Given/@When/@Then</b> correspond to the keyword used in the step</li>
<li>the pattern specified in the annotation is matching the step, using place holders of the parameters</li>
</ul>

<div class="clear">
<hr />
</div>

</body>
</html>
